<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<STYLE TYPE="text/css">
		BODY {
			background-color: f5f5f5;
			font-family: arial, verdana; font-size: small;
		}
		H2, H3, A, .tfc {
			color: #000080;
			font-family: arial, verdana; font-size: small;
		}
		PRE { 
		    font-family: monospace;
			border: 1px lightgrey dotted;
		    white-space: pre; 
		    color: black;
		    background-color: #efefef; 
		}
		TABLE {
			float: right;
			border-collapse: collapse;
			border-top: 1px solid #000000;
			border-right: 1px solid #000000;
			border-left: 1px solid #000000;
		}
		TH {
			padding-top: 2px;
			padding-bottom: 2px;
			padding-right: 5px;
			padding-left: 5px;
		}
		TD {
			padding-top: 2px;
			padding-bottom: 2px;
			padding-right: 5px;
			padding-left: 5px;
			border-bottom: 1px solid #000000;
			border-right: 1px solid #000000;
			font-family: arial, verdana; font-size: small;
		}
	</STYLE>
<TITLE>Varray</TITLE>
</HEAD>
<BODY>
<H1>20. Varray</H1>
The <I>varray</I>(3m) module is a variable array that permits quick access to elements by index without allocating all the memory for the array when the array is created. Instead, memory is allocated as necessary in increasingly larger chunks (32 * <tt>membsize</tt>, 64 * <tt>membsize</tt>, 128 * <tt>membsize</tt>, upto 2^20 * <tt>membsize</tt>).
<H3>20.1. Varray functions</H3>These functions should be used to manage <I>varray</I> objects.<A name="init"></A>
<P>
</P>
<B CLASS="tfc">The <TT>varray_init</TT> function</B>
<BR>
<B>Synopsis</B>
<PRE>
<BR>  #include &lt;mba/varray.h&gt;
  int varray_init(struct varray *va, size_t membsize, struct allocator *al);<BR>
</PRE>
<B>Description</B>
<BR>
The <TT>varray_init</TT> function with initialize the <TT>varray</TT> <tt>va</tt> with no initial elements. The size of each element in the array will be <tt>membsize</tt>. The <TT>allocator</TT> <tt>al</tt> will be used to allocate memory to back the array.
	<BR>
<B>Returns</B>
<BR>
The <TT>varray_init</TT> function returns 0 on success or -1 for failure in which case <tt>errno</tt> will be set to an appropriate value.
	<P>
</P>
<A name="deinit"></A>
<P>
</P>
<B CLASS="tfc">The <TT>varray_deinit</TT> function</B>
<BR>
<B>Synopsis</B>
<PRE>
<BR>  #include &lt;mba/varray.h&gt;
  int varray_deinit(struct varray *va);<BR>
</PRE>
<B>Description</B>
<BR>
The <TT>varray_deinit</TT> function deinitializes the <TT>varray</TT> <tt>va</tt> and releases any storage backing the array.
	<BR>
<B>Returns</B>
<BR>
The <TT>varray_deinit</TT> function returns 0 on success or -1 for failure in which case <tt>errno</tt> will be set to an appropriate value.
	<P>
</P>
<A name="new"></A>
<P>
</P>
<B CLASS="tfc">The <TT>varray_new</TT> function</B>
<BR>
<B>Synopsis</B>
<PRE>
<BR>  #include &lt;mba/varray.h&gt;
  struct varray *varray_new(size_t membsize, struct allocator *al);<BR>
</PRE>
<B>Description</B>
<BR>
The <TT>varray_new</TT> function allocates storage for a new <TT>varray</TT> object and initializes with the <TT>varray_init</TT> function.
	<BR>
<B>Returns</B>
<BR>
The <TT>varray_new</TT> function returns the new <tt>varray</tt> object or a null pointer if an error occurred in which case <tt>errno</tt> will be set appropriately.
	<P>
</P>
<A name="del"></A>
<P>
</P>
<B CLASS="tfc">The <TT>varray_del</TT> function</B>
<BR>
<B>Synopsis</B>
<PRE>
<BR>  #include &lt;mba/varray.h&gt;
  void varray_del(void *va);<BR>
</PRE>
<B>Description</B>
<BR>
The <TT>varray_del</TT> function calls <TT>varray_deinit</TT> on the object <tt>va</tt> and then frees the <tt>va</tt> object itself.
	<BR>
<P>
</P>
<A name="get"></A>
<P>
</P>
<B CLASS="tfc">The <TT>varray_get</TT> function</B>
<BR>
<B>Synopsis</B>
<PRE>
<BR>  #include &lt;mba/varray.h&gt;
  void *varray_get(struct varray *va, unsigned int idx);<BR>
</PRE>
<B>Description</B>
<BR>
The <TT>varray_get</TT> function returns a pointer to memory at index <tt>idx</tt>. The memory will be <tt>membsize</tt> bytes in size as specified in the <TT>varray_new</TT> function. The memory is initialized to 0 when the chunk backing it is allocated meaning the memory should initially be 0.
	<BR>
<B>Returns</B>
<BR>
The <TT>varray_get</TT> function returns a pointer to the memory at index <tt>idx</tt> or a null pointer if an error occured in which case errno will be set appropriately.
	<P>
</P>
<A name="index"></A>
<P>
</P>
<B CLASS="tfc">The <TT>varray_index</TT> function</B>
<BR>
<B>Synopsis</B>
<PRE>
<BR>  #include &lt;mba/varray.h&gt;
  int varray_index(struct varray *va, void *elem);<BR>
</PRE>
<B>Description</B>
<BR>
The <TT>varray_index</TT> function returns the index of the element <tt>elem</tt>. If the element is not found -1 is returned and <TT>errno</TT> is set to <tt>EFAULT</tt>.
	<BR>
<B>Returns</B>
<BR>
The <TT>varray_index</TT> function returns the index of the element or -1 and sets <TT>errno</TT> to <tt>EFAULT</tt> to indicate the element is not in the array.
	<P>
</P>
<A name="release"></A>
<P>
</P>
<B CLASS="tfc">The <TT>varray_release</TT> function</B>
<BR>
<B>Synopsis</B>
<PRE>
<BR>  #include &lt;mba/varray.h&gt;
  void varray_release(struct varray *va, unsigned int from);<BR>
</PRE>
<B>Description</B>
<BR>
The <TT>varray_release</TT> function may release all memory chunks storing elements from index <tt>from</tt> and higher. This function will only free memory chunks that constitute elements at the <tt>from</tt> index and above. If the <tt>from</tt> index is the first element of a chunk, that chunk will be freed as well. This function should only be used if it is understood that the range of elements being accessed has been significantly reduced such that memory will not be frequently allocated and freed.
	<BR>
<P>
</P>
<A name="iterate"></A>
<P>
</P>
<B CLASS="tfc">The <TT>varray_iterate</TT> function</B>
<BR>
<B>Synopsis</B>
<PRE>
<BR>  #include &lt;mba/varray.h&gt;
  void varray_iterate(void *va, iter_t *iter);<BR>
</PRE>
<B>Description</B>
<BR>
The <TT>varray_iterate</TT> and <TT>varray_next</TT> functions will enumerate over every element in the array that has ever been accessed with the <tt>varray_get</tt> function. However, adjacent elements in the same memory chunk will also be returned by <tt>varray_next</tt> even if they those elements have never been accessed with <tt>varray_get</tt>. Similarly, there may be gaps in the full range that are not returned by <tt>varray_next</tt> because no element was accessed in a range necessary for the chunk of memory for that range to be allocated. The <tt>varray_iterate</tt> function initializes the <tt>iter</tt> object to point to the beginning of the array. The <tt>varray_next</tt> function returns each element in the array or <tt>NULL</tt> if all elements have been enumerated.
	<BR>
<P>
</P>
<A name="next"></A>
<P>
</P>
<B CLASS="tfc">The <TT>varray_next</TT> function</B>
<BR>
<B>Synopsis</B>
<PRE>
<BR>  #include &lt;mba/varray.h&gt;
  void *varray_next(void *va, iter_t *iter);<BR>
</PRE>
<B>Returns</B>
<BR>
The <TT>varray_next</TT> function returns a pointer to the memory of the next element in the enumeration or a null pointer if there are no more elements to be enumerated.
	<P>
</P>
<HR NOSHADE>
<small>
Copyright 2003 Michael B. Allen &lt;mba2000 ioplex.com&gt;
</small>
</BODY>
</HTML>
